home *** CD-ROM | disk | FTP | other *** search
/ Sound Fx / Sound Fx.iso / Software / UNZIPED / DWSTK / DWS.H < prev    next >
Text File  |  1996-10-13  |  13KB  |  400 lines
  1. /******************************************************************************
  2. File:          dws.h
  3. Version:     2.22
  4. Tab stops: every 2 columns
  5. Project:     DiamondWare's Sound ToolKit
  6. Copyright: 1994-1995 DiamondWare, Ltd.    All rights reserved.
  7. Written:     by Keith Weiner and Erik Lorenzen
  8. Purpose:     Contains declarations for the DW Sound ToolKit
  9. History:     94/08/24 KW Started
  10.                      95/02/17 EL Finalized for 1.0
  11.                      95/03/19 EL Finalized for 1.01, Added new define dws_BUSY
  12.                      95/04/06 EL Finalized for 1.02, Added new define dws_IRQDISABLED
  13.                      95/06/16 EL Finalized for 1.03
  14.                      95/07/23 EL Finalized for 1.04, no changes
  15.                      95/08/01 EL Finalized for 2.00, added new defines for pmode errors
  16.                                                                                      & calling conventions
  17.                      95/08/29 EL Finalized for 2.10, no changes
  18.                      95/10/18 EL Finalized for 2.20, no changes
  19.                      95/12/07 EL Finalized for 2.21, no changes
  20.                      96/10/11 EL Finalized for 2.22, added some more VDS errors
  21.  
  22. ******************************************************************************/
  23.  
  24.  
  25.  
  26. #ifndef dws_INCLUDE
  27.  
  28.     #define dws_INCLUDE
  29.  
  30.  
  31.  
  32.     #ifdef __FLAT__
  33.         #define dws_CALLCON _cdecl
  34.         #define dws_DIST
  35.     #else
  36.         #define dws_CALLCON _far _pascal
  37.         #define dws_DIST _far
  38.     #endif
  39.  
  40.  
  41.  
  42. /*****************************************************************************/
  43.     /*
  44.      . The following is interrupt range that STK can become
  45.      . resident in.
  46.     */
  47.     #define dws_FIRSTINT 0x60
  48.     #define dws_LASTINT  0x66
  49. /*****************************************************************************/
  50.     /*
  51.      . The following is the complete list of possible values for dws_ErrNo.
  52.      . dws_ErrNo may be set by any dws_ function.  Check its value whenever
  53.      . the return value of a dws_ function is 0 (error).
  54.     */
  55.     #define dws_EZERO                                                      0     /* no error */
  56.  
  57.     /* The following 3 errors may be triggered by any dws_ function */
  58.     #define dws_NOTINITTED                                             1
  59.     #define dws_ALREADYINITTED                                     2
  60.     #define dws_NOTSUPPORTED                                         3
  61.  
  62.     /* The following 4 errors may be triggered by dws_DetectHardWare */
  63.     #define dws_DetectHardware_UNSTABLESYSTEM      4
  64.     #define dws_DetectHardware_BADBASEPORT             5
  65.     #define dws_DetectHardware_BADDMA                      6
  66.     #define dws_DetectHardware_BADIRQ                      7
  67.  
  68.     /* The following error may be triggered by dws_Kill */
  69.     #define dws_Kill_CANTUNHOOKISR                             8
  70.  
  71.     /* The following error may be triggered by any dws_X (mixer) function */
  72.     #define dws_X_BADINPUT                                             9
  73.  
  74.     /* The following 3 errors may be triggered by any dws_D (dig) function */
  75.     #define dws_D_NOTADWD                                              10
  76.     #define dws_D_NOTSUPPORTEDVER                              11
  77.     #define dws_D_INTERNALERROR                                  12
  78.  
  79.     /* The following error may be triggered by dws_DPlay */
  80.     #define dws_DPlay_NOSPACEFORSOUND                      13
  81.  
  82.     /* The following 2 errors may be triggered by dws_DSetRate */
  83.     #define dws_DSetRate_FREQTOLOW                             14
  84.     #define dws_DSetRate_FREQTOHIGH                          15
  85.  
  86.     /* The following 3 errors may be triggered by dws_MPlay */
  87.     #define dws_MPlay_NOTADWM                                      16
  88.     #define dws_MPlay_NOTSUPPORTEDVER                      17
  89.     #define dws_MPlay_INTERNALERROR                          18
  90.  
  91.     /*
  92.      . The following error may be triggered by any dws_ function
  93.      . (except dws_ErrNo and dws_Init) if called from an Interrupt
  94.      . Service Routine (ISR).  If you're not sure whether this applies
  95.      . to you: it probably doesn't.
  96.     */
  97.     #define dws_BUSY                                                         19
  98.  
  99.     /*
  100.      . The following error may be triggered by dws_Init, dws_Kill,
  101.      . and dws_DetectHardware.    It will only occur if interrupts are
  102.      . disabled.    Interrupts must be enabled when calling.    If you're
  103.      . not sure whether this applies to you: it probably doesn't.
  104.     */
  105.     #define dws_IRQDISABLED                                          20
  106.  
  107.  
  108.  
  109.     /*
  110.      . The following errors will only come up when using the protected mode
  111.      . extension to the STK
  112.     */
  113.     #define dws_NOTRESIDENT                                          100
  114.     #define dws_NOMEM                                                      101
  115.  
  116.  
  117.  
  118. /*---------------------------------------------------------------------------*/
  119.  
  120.  
  121.     /*
  122.      . The follwing section defines bitfields which are used by various
  123.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  124.      . set/reset independantly of all other bits.
  125.     */
  126.  
  127.     /* The following 2 consts indicate the capabilities of the user's hardware */
  128.     #define dws_capability_FM                                      0x0001
  129.     #define dws_capability_DIG                                     0x0002
  130.  
  131.     /* The following 2 consts indicate the status of specified digital sounds */
  132.     #define dws_DSOUNDSTATUSPLAYING                          0x0001
  133.     #define dws_DSOUNDSTATUSSEQUENCED                      0x0002
  134.  
  135.     /* The following 2 consts indicate the status of music playback */
  136.     #define dws_MSONGSTATUSPLAYING                             0x0001
  137.     #define dws_MSONGSTATUSPAUSED                              0x0002
  138. /*****************************************************************************/
  139.  
  140.  
  141.  
  142.     /*
  143.      . The following 3 types are used by the STK
  144.      .
  145.      . If you are already typedefing these names, simply put the line
  146.      .     #define stddef_INCLUDE
  147.      . before the line
  148.      .     #include <dws.h>
  149.      . in every source file which references the STK.
  150.     */
  151.     #ifndef stddef_INCLUDE
  152.         typedef unsigned char  byte;
  153.         typedef unsigned short word;
  154.         typedef unsigned long  dword;
  155.     #endif
  156.  
  157.  
  158.  
  159. /*****************************************************************************/
  160.  
  161.  
  162.  
  163.     /*
  164.      . The following section typedefs the structs used by the STK.    In each
  165.      . case, the user must create an instance of the struct prior to making
  166.      . a call to an STK function which takes a pointer to it.  The STK does
  167.      . not keep a pointer to any of these structs internally; after the call
  168.      . returns, you may deallocate it, if you wish.
  169.      .
  170.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  171.     */
  172.  
  173.  
  174.     /*
  175.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  176.      . about the installed hardware.    This is useful if detecting DMA channel,
  177.      . for example, consistently causes a machine lockup.  To override the
  178.      . autodetect for a setting, set the corresponding field in this struct
  179.      . to the correct value.    Otherwise, set the field to ffff hex.  Since
  180.      . the autodetect is reliable, this is the recommended course of action,
  181.      . except in cases of known problems.
  182.     */
  183.     typedef struct
  184.     {
  185.         word baseport;                /* base address of sound card (often 220 hex) */
  186.         word digdma;                    /* DMA channel */
  187.         word digirq;                    /* IRQ level */
  188.  
  189.         byte reserved[10];
  190.  
  191.     } dws_DETECTOVERRIDES;
  192.  
  193.  
  194.     /*
  195.      . A pointer to this struct is passed to dws_DetectHardWare, which fills
  196.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  197.      . writing this struct out to a file, it's important that you write
  198.      . the entire contents.  There is information (for internal STK use only)
  199.      . in the reserved[] field!
  200.     */
  201.     typedef struct
  202.     {
  203.         word baseport;                /* base address of sound card (often 220 hex) */
  204.         word capability;            /* see #defines, above */
  205.  
  206.         /* The following 3 fields are only valid if FM music is supported */
  207.         word mustyp;                    /* 0=none, 1=OPL2 */
  208.         word musnchan;                /* 1=mono */
  209.         word musnvoice;             /* number of voices supported by hardware(11 for FM) */
  210.  
  211.         /* The following 2 fields are only valid if digitized sound is supported */
  212.         word dignbits;                /* 0=none, 8=8 bit */
  213.         word dignchan;                /* 1=mono */
  214.  
  215.         word digdma;                    /* DMA channel */
  216.         word digirq;                    /* IRQ level */
  217.  
  218.         word mixtyp;                    /* 1=software, 2+ is hardware */
  219.  
  220.         byte reserved[44];        /* there are important values in here... */
  221.  
  222.     } dws_DETECTRESULTS;
  223.  
  224.  
  225.     /*
  226.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  227.      . allows the user to tell the STK to use less than the full capabilities
  228.      . of the installed sound hardware, and/or the user's sound board
  229.      . may not support every feature of the STK.
  230.     */
  231.     typedef struct
  232.     {
  233.         word musictyp;                /* 0=No Music, 1=OPL2 */
  234.  
  235.         word digtyp;                    /* 0=No Dig, 8=8bit */
  236.         word digrate;                 /* sampling rate, in Hz */
  237.         word dignvoices;            /* number of voices (up to 16) */
  238.         word dignchan;                /* 1=mono */
  239.  
  240.         byte reserved[6];
  241.  
  242.     } dws_IDEAL;
  243.  
  244.  
  245.     /*
  246.      . A pointer to this struct is passed to dws_DPlay.
  247.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  248.     */
  249.     typedef struct
  250.     {
  251.         byte dws_DIST *snd;     /* pointer to buffer which holds a .DWD file */
  252.         word count;                     /* number of times to play, or 0=infinite loop */
  253.         word priority;                /* higher numbers mean higher priority */
  254.         word presnd;                    /* soundnum to sequence sound _after_ */
  255.         word soundnum;                /* dws_DPlay returns a snd number from 10-65535 */
  256.  
  257.         byte reserved[20];
  258.  
  259.     } dws_DPLAY;
  260.  
  261.  
  262.     /* A pointer to this struct is passed to dws_MPlay. */
  263.     typedef struct
  264.     {
  265.         byte dws_DIST *track; /* pointer to buffer which holds a .DWM file */
  266.         word count;                     /* number of times to play, or 0=infinite loop */
  267.  
  268.         byte reserved[10];
  269.  
  270.     } dws_MPLAY;
  271.  
  272.  
  273. /*****************************************************************************/
  274.  
  275.  
  276.  
  277.     #ifdef __cplusplus
  278.         extern "C" {
  279.     #endif
  280.  
  281.  
  282.  
  283. /*****************************************************************************/
  284.  
  285.  
  286.     /*
  287.      . This function is callable at any time.  It returns the number of the
  288.      . last error which occured.
  289.     */
  290.     word    dws_CALLCON dws_ErrNo(void);
  291. /*---------------------------------------------------------------------------*/
  292.  
  293.  
  294.     /*
  295.      . This function is called at the end of the timer ISR (interrupt service
  296.      . routine).    If you're using the optional DWT (DW Timer), this happens
  297.      . automagically.  If you wrote your own timer handler routine, you must
  298.      . call this function regularly.
  299.     */
  300.     void    dws_CALLCON dws_Update(void);
  301. /*---------------------------------------------------------------------------*/
  302.  
  303.  
  304.     /*
  305.      . Each function in this section has a boolean return value.    A 0 (false)
  306.      . indicates that the function failed in some way.    In this case, call
  307.      . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  308.      . (true) indicates that all is well.
  309.     */
  310.     word    dws_CALLCON dws_DetectHardWare(dws_DETECTOVERRIDES dws_DIST *dov,
  311.                                                                              dws_DETECTRESULTS dws_DIST *dr);
  312.  
  313.     word    dws_CALLCON dws_Init(dws_DETECTRESULTS dws_DIST *dr,
  314.                                                          dws_IDEAL dws_DIST *ideal);
  315.  
  316.     /*
  317.      . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  318.      . terminates.
  319.      .
  320.      . NB: Trap critical errors.    Don't let DOS put up the
  321.      .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  322.     */
  323.     word    dws_CALLCON dws_Kill(void);
  324.  
  325.  
  326.     /*
  327.      . The following 3 functions comprise the mixer section of the STK.  A
  328.      . value of 0 turns a channel off; a value of 255 is the loudest.
  329.     */
  330.     word    dws_CALLCON dws_XMaster(word volume);
  331.  
  332.     word    dws_CALLCON dws_XMusic(word volume);
  333.  
  334.     word    dws_CALLCON dws_XDig(word volume);
  335.  
  336.  
  337.     /*
  338.      . The following 10 functions comprise the digitized sound functions of
  339.      . the STK.  See the documentation for complete details.
  340.     */
  341.     word    dws_CALLCON dws_DPlay(dws_DPLAY dws_DIST *dplay);
  342.  
  343.     word    dws_CALLCON dws_DSoundStatus(word soundnumber,
  344.                                                                          word dws_DIST *result);
  345.  
  346.     word    dws_CALLCON dws_DSetRate(word frequency);
  347.  
  348.     word    dws_CALLCON dws_DGetRate(word dws_DIST *result);
  349.  
  350.     /* This function is callable at any time*/
  351.     word    dws_CALLCON dws_DGetRateFromDWD(byte dws_DIST *snd,
  352.                                                                                 word dws_DIST *result);
  353.  
  354.     word    dws_CALLCON dws_DDiscard(word soundnum);
  355.  
  356.     word    dws_CALLCON dws_DDiscardAO(byte dws_DIST *snd);
  357.  
  358.     word    dws_CALLCON dws_DClear(void);                      /* Affects all sounds */
  359.  
  360.     word    dws_CALLCON dws_DPause(void);                      /* Affects all sounds */
  361.  
  362.     word    dws_CALLCON dws_DUnPause(void);                  /* Affects all sounds */
  363.  
  364.  
  365.     /*
  366.      . The following 5 functions comprise the music functions of the STK.
  367.      . See the documentation for complete details.
  368.     */
  369.     word    dws_CALLCON dws_MPlay(dws_MPLAY dws_DIST *mplay);
  370.  
  371.     word    dws_CALLCON dws_MSongStatus(word dws_DIST *result);
  372.  
  373.     word    dws_CALLCON dws_MClear(void);                      /* Kill playing song */
  374.  
  375.     word    dws_CALLCON dws_MPause(void);                      /* Pauses music playback */
  376.  
  377.     word    dws_CALLCON dws_MUnPause(void);                  /* UnPauses music playback */
  378.  
  379.  
  380.  
  381.     #ifndef __FLAT__
  382.         /*
  383.          . The following function is for creating a real-mode wrapper (for use
  384.          . by protected-mode).    It's installed as an interrupt handler on a
  385.          . "user" interrupt vector (0x60-0x66).  See stkrun.c.
  386.         */
  387.         void    dws_CALLCON dws_WRAP(void);
  388.     #endif
  389. /*****************************************************************************/
  390.  
  391.  
  392.  
  393.     #ifdef __cplusplus
  394.         }
  395.     #endif
  396.  
  397.  
  398.  
  399. #endif
  400.